Frontend WebHID Device Enumeration: Connected Device Discovery with JavaScript

WebHID API این پتانسیل را باز می‌کند که برنامه‌های وب بتوانند مستقیماً با طیف گسترده‌ای از دستگاه‌های رابط انسانی (HID) که معمولاً فقط برای برنامه‌های بومی در دسترس هستند، ارتباط برقرار کنند. این امر امکانات هیجان‌انگیزی را برای ایجاد تجربه‌های وب نوآورانه که با سخت‌افزارهای تخصصی مانند کنترلرهای بازی، دستگاه‌های ورودی سفارشی، ابزارهای علمی و موارد دیگر تعامل دارند، باز می‌کند. این راهنمای جامع به مفهوم اصلی شمارش دستگاه می‌پردازد، که اولین گام حیاتی در ایجاد ارتباط با یک دستگاه HID مورد نظر است.

What is the WebHID API?

WebHID API به برنامه‌های وب اجازه می‌دهد تا به دستگاه‌های رابط انسانی دسترسی داشته باشند. این دستگاه‌ها دسته گسترده‌ای را شامل می‌شوند، از جمله:

• Game Controllers: Joysticks, gamepads, racing wheels
• Input Devices: Keyboards, mice, trackballs
• Industrial Controls: Specialized control panels, sensor interfaces
• Scientific Instruments: Data acquisition devices, measurement tools
• Custom Hardware: Bespoke input devices created for specific purposes

برخلاف APIهای مرورگر قدیمی‌تر که پشتیبانی محدودی از HID ارائه می‌دادند، WebHID API دسترسی مستقیم به دستگاه‌های HID را فراهم می‌کند و توسعه‌دهندگان را قادر می‌سازد تا برنامه‌های وب غنی‌تر و تعاملی‌تری ایجاد کنند. تصور کنید که یک بازوی رباتیک را در یک آزمایشگاه از راه دور کنترل می‌کنید، یک مدل سه‌بعدی را با یک دستگاه ورودی سفارشی دستکاری می‌کنید، یا داده‌های حسگر را مستقیماً در یک داشبورد مبتنی بر وب دریافت می‌کنید - همه اینها در داخل مرورگر.

Understanding HID Device Enumeration

قبل از اینکه بتوانید با یک دستگاه HID تعامل داشته باشید، برنامه وب شما باید کشف کند که کدام دستگاه‌ها به سیستم کاربر متصل هستند. این فرآیند device enumeration نامیده می‌شود. WebHID API مکانیزمی را برای درخواست دسترسی به دستگاه‌های HID خاص بر اساس شناسه فروشنده (VID) و شناسه محصول (PID) یا با استفاده از یک فیلتر گسترده‌تر فراهم می‌کند.

این فرآیند معمولاً شامل این مراحل است:

1. Requesting Device Access: برنامه وب از کاربر می‌خواهد که یک دستگاه HID را با استفاده از navigator.hid.requestDevice() انتخاب کند.
2. Filtering Devices: می‌توانید فیلترهایی را برای محدود کردن لیست دستگاه‌های ارائه شده به کاربر مشخص کنید. این فیلترها بر اساس VID و PID دستگاه هستند.
3. Handling Device Selection: کاربر یک دستگاه را از لیست انتخاب می‌کند.
4. Opening the Device: برنامه یک اتصال به دستگاه انتخاب شده باز می‌کند.
5. Data Transfer: پس از ایجاد اتصال، برنامه می‌تواند داده‌ها را از دستگاه ارسال و دریافت کند.

Step-by-Step Guide to Device Enumeration

1. Requesting Device Access with Filters

متد navigator.hid.requestDevice() نقطه ورود برای درخواست دسترسی به دستگاه‌های HID است. این متد یک آرگومان اختیاری `filters` می‌گیرد که آرایه‌ای از اشیاء است که VID و PID دستگاه‌هایی را که می‌خواهید پیدا کنید مشخص می‌کند.

در اینجا یک مثال از نحوه درخواست دسترسی به دستگاه با VID و PID خاص آورده شده است:

async function requestHIDDevice() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          vendorId: 0x1234, // Replace with your device's Vendor ID
          productId: 0x5678 // Replace with your device's Product ID
        },
        // Add more filters for other devices if needed
      ]
    });

    if (devices.length > 0) {
      const device = devices[0]; // Use the first selected device
      console.log("HID Device Found:", device);
      // Open the device and start communication
      await openHIDDevice(device);
    } else {
      console.log("No HID device selected.");
    }
  } catch (error) {
    console.error("Error requesting HID device:", error);
  }
}

// Example usage (e.g., triggered by a button click):
document.getElementById('requestButton').addEventListener('click', requestHIDDevice);

Important Considerations:

• Vendor ID (VID) and Product ID (PID): اینها شناسه‌های منحصربه‌فردی هستند که به دستگاه‌های USB و بلوتوث اختصاص داده شده‌اند. شما باید VID و PID دستگاه مورد نظر خود را از مستندات سازنده یا با استفاده از ابزارهای سیستم (به عنوان مثال، Device Manager در ویندوز، System Information در macOS یا `lsusb` در لینوکس) بدست آورید.
• User Consent: متد requestDevice() یک اعلان مجوز کنترل شده توسط مرورگر را به کاربر نمایش می‌دهد و به آنها اجازه می‌دهد تا انتخاب کنند که کدام دستگاه‌های HID را برای دسترسی اعطا کنند. این یک اقدام امنیتی حیاتی برای جلوگیری از دسترسی وب‌سایت‌های مخرب به سخت‌افزار حساس بدون رضایت کاربر است.
• Multiple Filters: می‌توانید فیلترهای متعددی را در آرایه `filters` قرار دهید تا دسترسی به دستگاه‌هایی با VID و PID مختلف را درخواست کنید. این در صورتی مفید است که برنامه شما از چندین پیکربندی سخت‌افزاری پشتیبانی کند.

2. Obtaining Device Information

هنگامی که کاربر یک دستگاه را انتخاب کرد، متد requestDevice() آرایه‌ای از اشیاء HIDDevice را برمی‌گرداند. هر شیء HIDDevice حاوی اطلاعاتی در مورد دستگاه است، مانند VID، PID، usagePage، usage و collections. می‌توانید از این اطلاعات برای شناسایی و پیکربندی بیشتر دستگاه استفاده کنید.

async function openHIDDevice(device) {
  try {
    await device.open();
    console.log("HID Device Opened:", device.productName);

    // Listen for input reports
    device.addEventListener("inputreport", event => {
      const { data, reportId } = event;
      const uint8Array = new Uint8Array(data.buffer);
      console.log(`Received input report ${reportId}:`, uint8Array);
      // Process the input report data
    });

    device.addEventListener("disconnect", event => {
      console.log("HID Device Disconnected:", device.productName);
      // Handle device disconnection
    });

  } catch (error) {
    console.error("Error opening HID device:", error);
  }
}

Device Properties:

• vendorId: شناسه فروشنده دستگاه.
• productId: شناسه محصول دستگاه.
• productName: نام قابل خواندن توسط انسان محصول.
• collections: آرایه‌ای از اشیاء HIDCollectionInfo که مجموعه‌های HID دستگاه (گزارش‌ها، ویژگی‌ها و غیره) را توصیف می‌کنند. این می‌تواند بسیار پیچیده باشد و فقط برای دستگاه‌های پیچیده مورد نیاز است.

3. Handling Device Connection and Disconnection

WebHID API رویدادهایی را برای اطلاع رسانی به برنامه شما در هنگام اتصال یا قطع اتصال یک دستگاه ارائه می‌دهد. می‌توانید به رویدادهای connect و disconnect در شیء navigator.hid گوش دهید.

navigator.hid.addEventListener("connect", event => {
  const device = event.device;
  console.log("HID Device Connected:", device);
  // Handle device connection (e.g., re-open the device)
});

navigator.hid.addEventListener("disconnect", event => {
  const device = event.device;
  console.log("HID Device Disconnected:", device);
  // Handle device disconnection (e.g., clean up resources)
});

Best Practices for Connection Management:

• Re-enumeration on Connect: هنگامی که یک دستگاه متصل می‌شود، اغلب بهتر است دستگاه‌ها را دوباره شمارش کنید تا مطمئن شوید که برنامه شما یک لیست به‌روز دارد.
• Resource Cleanup on Disconnect: هنگامی که یک دستگاه قطع می‌شود، هر منبع مرتبط با آن را آزاد کنید (به عنوان مثال، اتصال دستگاه را ببندید، شنوندگان رویداد را حذف کنید).
• Error Handling: مدیریت خطای قوی را پیاده‌سازی کنید تا به طور ظریف موقعیت‌هایی را که یک دستگاه با شکست مواجه می‌شود یا به طور غیرمنتظره قطع می‌شود، مدیریت کنید.

Advanced Device Filtering Techniques

فراتر از فیلتر کردن VID و PID اساسی، WebHID API تکنیک‌های پیشرفته‌تری را برای هدف قرار دادن دستگاه‌های خاص ارائه می‌دهد. این امر به ویژه هنگام برخورد با دستگاه‌هایی که دارای چندین رابط یا عملکرد هستند مفید است.

1. Filtering by Usage Page and Usage

دستگاه‌های HID به *صفحات استفاده* و *استفاده‌ها* سازماندهی می‌شوند که نوع عملکردی را که یک دستگاه ارائه می‌دهد تعریف می‌کنند. به عنوان مثال، یک صفحه کلید متعلق به صفحه استفاده "Generic Desktop" است و دارای استفاده "Keyboard" است. می‌توانید دستگاه‌ها را بر اساس صفحه استفاده و استفاده آنها فیلتر کنید تا انواع دستگاه‌های خاص را هدف قرار دهید.

async function requestSpecificKeyboard() {
  try {
    const devices = await navigator.hid.requestDevice({
      filters: [
        {
          usagePage: 0x01, // Generic Desktop Page
          usage: 0x06      // Keyboard Usage
        }
      ]
    });

    // ... (rest of the code to handle the device)
  } catch (error) {
    console.error("Error requesting HID device:", error);
  }
}

Finding Usage Page and Usage Values:

• HID Usage Tables: جداول استفاده رسمی HID (منتشر شده توسط USB Implementers Forum) صفحات استفاده و استفاده‌های استاندارد شده را برای انواع دستگاه‌های مختلف تعریف می‌کنند.
• Device Documentation: مستندات سازنده دستگاه ممکن است صفحات استفاده و مقادیر استفاده را برای دستگاه خود مشخص کند.
• HID Report Descriptors: برای سناریوهای پیشرفته، می‌توانید توصیفگر گزارش HID یک دستگاه را تجزیه و تحلیل کنید تا صفحات استفاده و استفاده‌های پشتیبانی شده آن را تعیین کنید.

2. Handling Multiple Interfaces

برخی از دستگاه‌های HID چندین رابط را در معرض دید قرار می‌دهند که هر کدام مجموعه عملکردهای خاص خود را دارند. WebHID API هر رابط را به عنوان یک دستگاه HID جداگانه در نظر می‌گیرد. برای دسترسی به یک رابط خاص، ممکن است لازم باشد فیلتر کردن VID/PID را با فیلتر کردن صفحه استفاده/استفاده ترکیب کنید تا رابط مورد نظر را هدف قرار دهید.

Practical Examples and Use Cases

1. Building a Custom Game Controller Interface

تصور کنید که در حال ساخت یک بازی مبتنی بر وب هستید و می‌خواهید از یک کنترلر بازی سفارشی پشتیبانی کنید. می‌توانید از WebHID API برای خواندن مستقیم ورودی از دکمه‌های کنترلر، جوی استیک‌ها و سایر کنترل‌ها استفاده کنید. این به شما امکان می‌دهد تا یک تجربه بازی بسیار پاسخگو و فراگیر ایجاد کنید.

2. Creating a Web-Based MIDI Controller

نوازندگان و مهندسان صدا می‌توانند از کنترلرهای MIDI مبتنی بر وب که با ایستگاه‌های کاری صوتی دیجیتال (DAW) یا سینتی‌سایزرها تعامل دارند، بهره‌مند شوند. WebHID API شما را قادر می‌سازد تا کنترلرهای MIDI سفارشی ایجاد کنید که پیام‌های MIDI را مستقیماً در مرورگر ارسال و دریافت می‌کنند.

3. Interacting with Scientific Instruments

محققان و دانشمندان می‌توانند از WebHID API برای ارتباط با ابزارهای علمی، مانند دستگاه‌های جمع‌آوری داده، حسگرها و ابزارهای اندازه‌گیری استفاده کنند. این به آنها امکان می‌دهد تا داده‌ها را مستقیماً در یک داشبورد یا ابزار تجزیه و تحلیل مبتنی بر وب جمع‌آوری و تجزیه و تحلیل کنند.

4. Accessibility Applications

WebHID فرصت‌هایی را برای ایجاد فناوری‌های کمکی فراهم می‌کند. به عنوان مثال، دستگاه‌های ورودی تخصصی برای کاربران دارای اختلالات حرکتی می‌توانند مستقیماً در برنامه‌های وب ادغام شوند و تجربه‌های سفارشی‌تر و در دسترس‌تری را ارائه دهند. نمونه‌های جهانی ممکن است شامل ادغام دستگاه‌های ردیابی چشم تخصصی برای ناوبری بدون دست یا آرایه‌های دکمه‌ای قابل تنظیم برای دسترسی تک سوئیچی در زبان‌ها و روش‌های ورودی مختلف باشد.

Cross-Browser Compatibility and Security Considerations

1. Browser Support

WebHID API در حال حاضر در مرورگرهای مبتنی بر Chromium (کروم، اج، اپرا) پشتیبانی می‌شود و برای سایر مرورگرها در حال توسعه است. قبل از پیاده‌سازی WebHID API در برنامه خود، مهم است که سازگاری مرورگر را بررسی کنید و مکانیزم‌های بازگشتی را برای مرورگرهایی که از API پشتیبانی نمی‌کنند، ارائه دهید.

2. Security Considerations

WebHID API با در نظر گرفتن امنیت طراحی شده است. مرورگر قبل از اینکه به یک برنامه وب اجازه دسترسی به یک دستگاه HID را بدهد، از کاربر اجازه می‌گیرد. این امر مانع از دسترسی وب‌سایت‌های مخرب به سخت‌افزار حساس بدون رضایت کاربر می‌شود. علاوه بر این، WebHID API در داخل sandbox امنیتی مرورگر عمل می‌کند و دسترسی برنامه به منابع سیستم را محدود می‌کند.

• HTTPS Only: WebHID، مانند سایر APIهای وب قدرتمند، برای عملکرد به یک زمینه امن (HTTPS) نیاز دارد.
• User Gestures: درخواست دسترسی به دستگاه معمولاً به یک ژست کاربر (به عنوان مثال، کلیک دکمه) نیاز دارد تا از درخواست‌های دسترسی ناخواسته جلوگیری شود.
• Permissions API: از Permissions API می‌توان برای پرس و جو و مدیریت مجوزهای WebHID استفاده کرد.

Troubleshooting Common Issues

1. Device Not Found

اگر برنامه شما نتواند دستگاه HID را پیدا کند، VID و PID را دوباره بررسی کنید. اطمینان حاصل کنید که آنها با شناسه‌های واقعی دستگاه مطابقت دارند. همچنین، تأیید کنید که دستگاه به درستی متصل شده و توسط سیستم عامل شناسایی شده است.

2. Permission Denied

اگر کاربر دسترسی به دستگاه HID را رد کند، برنامه شما قادر به برقراری ارتباط با آن نخواهد بود. این سناریو را به طور ظریف مدیریت کنید و با نمایش یک پیام به کاربر و توضیح اینکه چرا دسترسی مورد نیاز است. در نظر بگیرید که راه‌های جایگزینی را برای کاربر برای تعامل با برنامه خود ارائه دهید.

3. Data Format Issues

دستگاه‌های HID اغلب از فرمت‌های داده سفارشی برای ارسال و دریافت داده استفاده می‌کنند. شما باید فرمت داده دستگاه را درک کنید و منطق تجزیه و سریال‌سازی مناسب را در برنامه خود پیاده‌سازی کنید. برای اطلاعات بیشتر در مورد فرمت داده، به مستندات سازنده دستگاه مراجعه کنید.

Conclusion

WebHID API توسعه‌دهندگان وب را قادر می‌سازد تا برنامه‌های وب نوآورانه و تعاملی ایجاد کنند که مستقیماً با دستگاه‌های رابط انسانی ارتباط برقرار می‌کنند. با درک اصول شمارش دستگاه، فیلتر کردن و مدیریت اتصال، می‌توانید پتانسیل کامل WebHID API را باز کنید و تجربه‌های کاربری جذابی ایجاد کنید. قدرت WebHID را برای اتصال وب به دنیای فیزیکی در آغوش بگیرید و امکانات جدیدی را برای خلاقیت، بهره‌وری و دسترسی در سراسر جهان پرورش دهید.

Further Resources

• WebHID API Specification
• WebHID API on Chrome Developers
• USB Implementers Forum (HID Information)